Create an Entity

Overview

This document describes how to create an entity in any work system using the SyncNow DevOps Gate. You can use Groovy scripts for Jenkins or copy cURL commands directly from the DevOps Gate project configuration in the SyncNow UI.

Overview

💡 Usage Examples

Create a bug when automated testing fails.
Create a bug when a security vulnerability is found.
Create a service ticket when an incident is identified in another system.

✨ Creating an Entity

This procedure creates an entity according to the mapping definition. If an entity with the same title/summary or matching a defined filter exists, SyncNow will update it instead of creating a duplicate.

Create An Entity

📨 API Request

The request URL should include the system ID, which can be copied from the DevOps Process definition page.

POST /api/v1.0/DevOpsGate/Enrich/{DevOpsProjectID}?action=create

Request Body Parameters:

Parameter	Description
Param1…ParamX	Parameters as defined in the DevOps Gate per entityType mapping
`subProject`	The target work system project as defined in the DevOps Gate Process. Work systems for publishing can be limited through SyncNow DevOps Process configuration
`entityType`	The entity to be created
`CreateIfEntityDoesNotExistByTitleOtherwiseUpdate`	Whether to create an entity if found a similar one with the same title

Sample Payload:

[
  {
    "fields": [
      { "key": "Param1", "value": "string" },
      { "key": "Param2", "value": "string" },
      { "key": "Param3", "value": "string" }
    ],
    "subProject": "MyProject",
    "entityType": "Bug",
    "CreateIfEntityDoesNotExistByTitleOtherwiseUpdate": "false"
  }
]

🟢 API Response

Field	Description
systemID	The system where the entities were created
entityKeys	The IDs of the entities created
errors	Errors that occurred during creation
warnings	Warnings that occurred during creation

Sample Response:

{
  "updatedEntitiesID": [
    {
      "systemID": "10",
      "entityKeys": ["CLS-3938"]
    }
  ],
  "errors": [],
  "warnings": []
}

🤖 Jenkins Groovy Script Example

Below is a Groovy code example for Jenkins that creates an entity with SyncNow DevOps Gate:

@NonCPS
def getCommentsString() {
    def list = []
    def changeLogSets = currentBuild.changeSets
    for (int i = 0; i < changeLogSets.size(); i++) {
        def entries = changeLogSets[i].items
        for (int j = 0; j < entries.length; j++) {
            def entry = entries[j]
            if (entry.msg != null) {
               list.add("""${entry.commitId} on ${new Date(entry.timestamp)}: ${entry.msg.replaceAll("[\n\r]", " ")}""")
            }
        }
    }
    return list.join(',')
}

pipeline {
    agent any
    stages {
        stage('Clone') { steps { echo 'Clone Code' } }
        stage('Version') { steps { echo 'Version' } }
        stage('Test') { steps { echo 'Test' } }
        stage('Build') { steps { echo 'Build' } }
        stage('Publish') { steps { echo 'Publish' } }
        stage('Notify SyncNow') {
            steps {
                echo 'Notify'
                echo "Job Name is ${JOB_NAME}, Build ID is ${env.BUILD_ID}"
                script {
                    def commits = getCommentsString()
                    def payload = """
[{
  "fields": [
    { "key": "Param1", "value": "string" },
    { "key": "Param2", "value": "string" },
    { "key": "Param3", "value": "string" }
  ],
  "subProject": "MyProject",
  "entityType": "Bug"
}]
                    """
                    def response = httpRequest acceptType: 'APPLICATION_JSON', contentType: 'APPLICATION_JSON', httpMode: 'POST', authentication: 'SyncNow', requestBody: "${payload}", url: "https://<SyncNowBaseURL>/api/v1.0/DevOpsGate/Enrich/<DevOpsProjectID>?action=create"
                    println("Status: ${response.status}")
                    println("Content: ${response.content}")
                }
            }
        }
    }
}

📝 Step-by-Step Instructions

Example: Create or Update an Entity

Create a DevOps Gate Process.
Navigate to the Mapping Entities page.
Go to the Mapping Options page for specific entity mappings.
Add filters (e.g., filter by Status).

Duplicate Detection: Entity names are always checked by their summary/title. If an entity with the same name/title and type is found, it will be updated.
Go to the DevOps Gate Process Configuration and press the How It Works link.
Select "Create & Update Entities from Commits".
Copy the cURL command.
Paste it into a command line. Set the correct sub-project and execute.
Change the content of the fields as needed and execute again.
A new entity will be created with information from both DevOps Gate calls.
Change the status of the entity.
Execute the cURL command again.
A new entity will be created.

Tip:
Use filters and duplicate detection to avoid creating unnecessary duplicates and to keep your work systems clean and up to date.